home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-STLport.exe / {app} / include / CEGUIEventSet.h < prev    next >
C/C++ Source or Header  |  2005-06-04  |  8KB  |  272 lines
  1. /************************************************************************
  2.     filename:     CEGUIEventSet.h
  3.     created:    21/2/2004
  4.     author:        Paul D Turner
  5.     
  6.     purpose:    Defines class for a named collection of Event objects
  7. *************************************************************************/
  8. /*************************************************************************
  9.     Crazy Eddie's GUI System (http://www.cegui.org.uk)
  10.     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
  11.  
  12.     This library is free software; you can redistribute it and/or
  13.     modify it under the terms of the GNU Lesser General Public
  14.     License as published by the Free Software Foundation; either
  15.     version 2.1 of the License, or (at your option) any later version.
  16.  
  17.     This library is distributed in the hope that it will be useful,
  18.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  19.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20.     Lesser General Public License for more details.
  21.  
  22.     You should have received a copy of the GNU Lesser General Public
  23.     License along with this library; if not, write to the Free Software
  24.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  25. *************************************************************************/
  26. #ifndef _CEGUIEventSet_h_
  27. #define _CEGUIEventSet_h_
  28.  
  29. #include "CEGUIBase.h"
  30. #include "CEGUIString.h"
  31. #include "CEGUIEvent.h"
  32. #include "CEGUIIteratorBase.h"
  33. #include <map>
  34.  
  35. #if defined (_MSC_VER)
  36. #    pragma warning(push)
  37. #    pragma warning(disable : 4251)
  38. #endif
  39.  
  40.  
  41. // Start of CEGUI namespace section
  42. namespace CEGUI
  43. {
  44. /*!
  45. \brief
  46.     Class that collects together a set of Event objects.
  47.  
  48.     The EventSet used to collect Event objects together, and allow access
  49.     to them by a unique name
  50. */
  51. class CEGUIEXPORT EventSet
  52. {
  53. public:
  54.     /*!
  55.     \brief
  56.         Constructor for EventSet objects
  57.     */
  58.     EventSet();
  59.  
  60.  
  61.     /*!
  62.     \brief
  63.         Destructor for EventSet objects
  64.     */
  65.     virtual ~EventSet(void);
  66.  
  67.  
  68.     /*!
  69.     \brief
  70.         Add a new Event to the EventSet with the given name.
  71.  
  72.     \param name
  73.         String object containing the name to give the new Event.  The name must be unique for the EventSet.
  74.  
  75.     \return
  76.         Nothing
  77.  
  78.     \exception AlreadyExistsException    Thrown if an Event already exists named \a name.
  79.     */
  80.     void    addEvent(const String& name);
  81.  
  82.  
  83.     /*!
  84.     \brief
  85.         Removes the Event with the given name.  All connections to the event are disconnected.
  86.  
  87.     \param name
  88.         String object containing the name of the Event to remove.  If no such Event exists, nothing happens.
  89.  
  90.     \return
  91.         Nothing.
  92.     */
  93.     void    removeEvent(const String& name);
  94.  
  95.  
  96.     /*!
  97.     \brief
  98.         Remove all Event objects from the EventSet
  99.  
  100.     \return
  101.         Nothing
  102.     */
  103.     void    removeAllEvents(void);
  104.  
  105.  
  106.     /*!
  107.     \brief
  108.         Checks to see if an Event with the given name is present in the EventSet.
  109.  
  110.     \return
  111.         true if an Event named \a name was found, or false if the Event was not found
  112.     */
  113.     bool    isEventPresent(const String& name);
  114.  
  115.  
  116.     /*!
  117.     \brief
  118.         Subscribes the named Event.
  119.  
  120.     \param name
  121.         String object containing the name of the Event to subscribe to.
  122.  
  123.     \param subscriber
  124.         Function or object that is to be subscribed to the Event.
  125.  
  126.     \return
  127.         Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.
  128.  
  129.     \exception UnknownObjectException    Thrown if an Event named \a name is not in the EventSet
  130.     */
  131.     virtual Event::Connection    subscribeEvent(const String& name, Event::Subscriber subscriber);
  132.  
  133.  
  134.     /*!
  135.     \brief
  136.         Subscribes the specified group of the named Event.
  137.  
  138.     \param name
  139.         String object containing the name of the Event to subscribe to.
  140.  
  141.     \param group
  142.         Group which is to be subscribed to.  Subscription groups are called in ascending order.
  143.  
  144.     \param subscriber
  145.         Function or object that is to be subscribed to the Event.
  146.  
  147.     \return
  148.         Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.
  149.  
  150.     \exception UnknownObjectException    Thrown if an Event named \a name is not in the EventSet
  151.     */
  152.     virtual Event::Connection    subscribeEvent(const String& name, Event::Group group, Event::Subscriber subscriber);
  153.     
  154.     
  155.     /*!
  156.     \brief
  157.         Subscribes the named Event to a scripted funtion
  158.  
  159.     \param name
  160.         String object containing the name of the Event to subscribe to.
  161.  
  162.     \param subscriber_name
  163.         String object containing the name of the script funtion that is to be subscribed to the Event.
  164.  
  165.     \return
  166.         Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.
  167.  
  168.     \exception UnknownObjectException    Thrown if an Event named \a name is not in the EventSet
  169.     */
  170.     virtual Event::Connection    subscribeScriptedEvent(const String& name, const String& subscriber_name);
  171.     
  172.     
  173.     /*!
  174.     \brief
  175.         Subscribes the specified group of the named Event to a scripted funtion.
  176.  
  177.     \param name
  178.         String object containing the name of the Event to subscribe to.
  179.  
  180.     \param group
  181.         Group which is to be subscribed to.  Subscription groups are called in ascending order.
  182.  
  183.     \param subscriber_name
  184.         String object containing the name of the script funtion that is to be subscribed to the Event.
  185.  
  186.     \return
  187.         Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.
  188.  
  189.     \exception UnknownObjectException    Thrown if an Event named \a name is not in the EventSet
  190.     */
  191.     virtual Event::Connection    subscribeScriptedEvent(const String& name, Event::Group group, const String& subscriber_name);
  192.  
  193.  
  194.     /*!
  195.     \brief
  196.         Fires the named event passing the given EventArgs object.
  197.  
  198.     \param name
  199.         String object holding the name of the Event that is to be fired (triggered)
  200.  
  201.     \param args
  202.         The EventArgs (or derived) object that is to be bassed to each subscriber of the Event.  Once all subscribers
  203.         have been called the 'handled' field of the event is updated appropriately.
  204.         
  205.     \param eventNamespace
  206.         String object describing the global event namespace prefix for this event.
  207.  
  208.     \return
  209.         Nothing.
  210.  
  211.     \exception UnknownObjectException    Thrown if no Event named \a name was found in the EventSet.
  212.     */
  213.     virtual void    fireEvent(const String& name, EventArgs& args, const String& eventNamespace = "");
  214.  
  215.  
  216.     /*!
  217.     \brief
  218.         Return whether the EventSet is muted or not.
  219.  
  220.     \return
  221.         - true if the EventSet is muted.  All requests to fire events will be ignored.
  222.         - false if the EventSet is not muted.  All requests to fire events are processed as normal.
  223.     */
  224.     bool    isMuted(void) const;
  225.  
  226.  
  227.     /*!
  228.     \brief
  229.         Set the mute state for this EventSet.
  230.  
  231.     \param setting
  232.         - true if the EventSet is to be muted (no further event firing requests will be honoured until EventSet is unmuted).
  233.         - false if the EventSet is not to be muted and all events should fired as requested.
  234.  
  235.     \return
  236.         Nothing.
  237.     */
  238.     void    setMutedState(bool setting);
  239.  
  240.  
  241. protected:
  242.     // Do not allow copying, assignment, or any other usage than simple creation.
  243.     EventSet(EventSet& e) {}
  244.     EventSet& operator=(EventSet& e) {return *this;}
  245.  
  246.     typedef std::map<String, Event*>    EventMap;
  247.     EventMap    d_events;
  248.  
  249.     bool    d_muted;    //!< true if events for this EventSet have been muted.
  250.  
  251. public:
  252.     /*************************************************************************
  253.         Iterator stuff
  254.     *************************************************************************/
  255.     typedef    ConstBaseIterator<EventMap>    EventIterator;
  256.  
  257.     /*!
  258.     \brief
  259.         Return a EventSet::EventIterator object to iterate over the available events.
  260.     */
  261.     EventIterator    getIterator(void) const;
  262. };
  263.  
  264. } // End of  CEGUI namespace section
  265.  
  266.  
  267. #if defined(_MSC_VER)
  268. #    pragma warning(pop)
  269. #endif
  270.  
  271. #endif    // end of guard _CEGUIEventSet_h_
  272.